<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8" />
    <title>Chapter 17.  The Memory Pool Subsystem</title>
    <link rel="stylesheet" href="gettingStarted.css" type="text/css" />
    <meta name="generator" content="DocBook XSL Stylesheets V1.73.2" />
    <link rel="start" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="up" href="index.html" title="Berkeley DB Programmer's Reference Guide" />
    <link rel="prev" href="log_limits.html" title="Log file limits" />
    <link rel="next" href="mp_config.html" title="Configuring the memory pool" />
  </head>
  <body>
    <div class="navheader">
      <table width="100%" summary="Navigation header">
        <tr>
          <th colspan="3" align="center">Chapter 17. 
		The Memory Pool Subsystem
        </th>
        </tr>
        <tr>
          <td width="20%" align="left"><a accesskey="p" href="log_limits.html">Prev</a> </td>
          <th width="60%" align="center"> </th>
          <td width="20%" align="right"> <a accesskey="n" href="mp_config.html">Next</a></td>
        </tr>
      </table>
      <hr />
    </div>
    <div class="chapter" lang="en" xml:lang="en">
      <div class="titlepage">
        <div>
          <div>
            <h2 class="title"><a id="mp"></a>Chapter 17. 
		The Memory Pool Subsystem
        </h2>
          </div>
        </div>
      </div>
      <div class="toc">
        <p>
          <b>Table of Contents</b>
        </p>
        <dl>
          <dt>
            <span class="sect1">
              <a href="mp.html#mp_intro">Introduction to the memory pool subsystem</a>
            </span>
          </dt>
          <dt>
            <span class="sect1">
              <a href="mp_config.html">Configuring the memory pool</a>
            </span>
          </dt>
        </dl>
      </div>
      <div class="sect1" lang="en" xml:lang="en">
        <div class="titlepage">
          <div>
            <div>
              <h2 class="title" style="clear: both"><a id="mp_intro"></a>Introduction to the memory pool subsystem</h2>
            </div>
          </div>
        </div>
        <p>The Memory Pool subsystem is the general-purpose shared memory buffer
pool used by Berkeley DB.  This module is useful outside of the Berkeley DB package
for processes that require page-oriented, shared and cached file 
access.  (However, such "use outside of Berkeley DB" is not supported
in replicated environments.)</p>
        <p>A <span class="emphasis"><em>memory pool</em></span> is a memory cache shared among any number of
threads of control.  The <a href="../api_reference/C/envopen.html#envopen_DB_INIT_MPOOL" class="olink">DB_INIT_MPOOL</a> flag to the
<a href="../api_reference/C/envopen.html" class="olink">DB_ENV-&gt;open()</a> method opens and optionally creates a memory pool.  When
that pool is no longer in use, it should be closed using the
<a href="../api_reference/C/envclose.html" class="olink">DB_ENV-&gt;close()</a> method.</p>
        <p>The <a href="../api_reference/C/mempfcreate.html" class="olink">DB_ENV-&gt;memp_fcreate()</a> method returns a <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle on an
underlying file within the memory pool.  The file may be opened using
the <a href="../api_reference/C/mempfopen.html" class="olink">DB_MPOOLFILE-&gt;open()</a> method. The <a href="../api_reference/C/mempfget.html" class="olink">DB_MPOOLFILE-&gt;get()</a> method is used to retrieve
pages from files in the pool.  All retrieved pages must be subsequently
returned using the <a href="../api_reference/C/mempput.html" class="olink">DB_MPOOLFILE-&gt;put()</a> method.  At the time pages are returned,
they may be marked <span class="bold"><strong>dirty</strong></span>, which causes them to be written to
the underlying file before being discarded from the pool.  If there is
insufficient room to bring a new page in the pool, a page is selected
to be discarded from the pool using a least-recently-used algorithm.
All dirty pages in the pool from the file may be flushed using the
<a href="../api_reference/C/mempfsync.html" class="olink">DB_MPOOLFILE-&gt;sync()</a> method.  When the file handle is no longer in use, it
should be closed using the <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE-&gt;close()</a> method.</p>
        <p>There are additional configuration interfaces that apply when opening
a new file in the memory pool:</p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>The <a href="../api_reference/C/mempset_clear_len.html" class="olink">DB_MPOOLFILE-&gt;set_clear_len()</a> method specifies the number of bytes to clear
when creating a new page in the memory pool.</li>
            <li>The <a href="../api_reference/C/mempset_fileid.html" class="olink">DB_MPOOLFILE-&gt;set_fileid()</a> method specifies a unique ID associated with the file.</li>
            <li>The <a href="../api_reference/C/mempset_ftype.html" class="olink">DB_MPOOLFILE-&gt;set_ftype()</a> method specifies the type of file for the purposes of
page input and output processing.</li>
            <li>The <a href="../api_reference/C/mempset_lsn_offset.html" class="olink">DB_MPOOLFILE-&gt;set_lsn_offset()</a> method specifies the byte offset of each page's
log sequence number (<a href="../api_reference/C/lsn.html" class="olink">DB_LSN</a>) for the purposes of transaction
checkpoints.</li>
            <li>The <a href="../api_reference/C/mempset_pgcookie.html" class="olink">DB_MPOOLFILE-&gt;set_pgcookie()</a> method specifies an application provided argument
for the purposes of page input and output processing.</li>
          </ul>
        </div>
        <p>There are additional interfaces for the memory pool as a whole:</p>
        <div class="itemizedlist">
          <ul type="disc">
            <li>It is possible to gradually flush buffers from the pool in order to
maintain a consistent percentage of clean buffers in the pool using
the <a href="../api_reference/C/memptrickle.html" class="olink">DB_ENV-&gt;memp_trickle()</a> method.</li>
            <li>Because special-purpose processing may be necessary when pages are read
or written (for example, endian conversion, or page checksums), the
<a href="../api_reference/C/mempregister.html" class="olink">DB_ENV-&gt;memp_register()</a> function allows applications to specify automatic
input and output processing in these cases.</li>
            <li>The <a href="../api_reference/C/db_stat.html" class="olink">db_stat utility</a> uses the <a href="../api_reference/C/mempstat.html" class="olink">DB_ENV-&gt;memp_stat()</a> method to display
statistics about the efficiency of the pool.</li>
            <li>All dirty pages in the pool may be flushed using the <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV-&gt;memp_sync()</a> method.
In addition, <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV-&gt;memp_sync()</a> takes an argument that is specific to
database systems, and which allows the memory pool to be flushed up to
a specified log sequence number (<a href="../api_reference/C/lsn.html" class="olink">DB_LSN</a>).</li>
            <li>The entire pool may be discarded using the <a href="../api_reference/C/envremove.html" class="olink">DB_ENV-&gt;remove()</a> method.</li>
          </ul>
        </div>
        <div class="informaltable">
          <table border="1" width="80%">
            <colgroup>
              <col />
              <col />
            </colgroup>
            <thead>
              <tr>
                <th>Memory Pools and Related Methods</th>
                <th>Description</th>
              </tr>
            </thead>
            <tbody>
              <tr>
                <td><a href="../api_reference/C/dbget_mpf.html" class="olink">DB-&gt;get_mpf()</a> handle</td>
                <td>Return <a href="../api_reference/C/db.html" class="olink">DB</a>'s underlying <a href="../api_reference/C/memp.html" class="olink">DB_MPOOLFILE</a> handle</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempstat.html" class="olink">DB_ENV-&gt;memp_stat()</a>
                </td>
                <td>Return memory pool statistics</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempsync.html" class="olink">DB_ENV-&gt;memp_sync()</a>
                </td>
                <td>Flush pages from a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/memptrickle.html" class="olink">DB_ENV-&gt;memp_trickle()</a>
                </td>
                <td>Trickle flush pages from a memory pool</td>
              </tr>
              <tr>
                <td>
                  <span class="emphasis">
                    <em>Memory Pool Configuration</em>
                  </span>
                </td>
                <td> </td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempregister.html" class="olink">DB_ENV-&gt;memp_register()</a>
                </td>
                <td>Register input/output functions for a file in a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/envset_cachesize.html" class="olink">DB_ENV-&gt;set_cachesize()</a>
                </td>
                <td>Set the environment cache size</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/envset_cache_max.html" class="olink">DB_ENV-&gt;set_cache_max()</a>
                </td>
                <td>Set the maximum cache size</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_mp_max_openfd.html" class="olink">DB_ENV-&gt;set_mp_max_openfd()</a>
                </td>
                <td>Set the maximum number of open file descriptors</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_mp_max_write.html" class="olink">DB_ENV-&gt;set_mp_max_write()</a>
                </td>
                <td>Set the maximum number of sequential disk writes</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/envset_mp_mmapsize.html" class="olink">DB_ENV-&gt;set_mp_mmapsize()</a>
                </td>
                <td>Set maximum mapped-in database file size</td>
              </tr>
              <tr>
                <td>
                  <span class="emphasis">
                    <em>Memory Pool Files</em>
                  </span>
                </td>
                <td> </td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempfcreate.html" class="olink">DB_ENV-&gt;memp_fcreate()</a>
                </td>
                <td>Create a memory pool file handle</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempfclose.html" class="olink">DB_MPOOLFILE-&gt;close()</a>
                </td>
                <td>Close a file in a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempfget.html" class="olink">DB_MPOOLFILE-&gt;get()</a>
                </td>
                <td>Get page from a file in a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempfopen.html" class="olink">DB_MPOOLFILE-&gt;open()</a>
                </td>
                <td>Open a file in a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempput.html" class="olink">DB_MPOOLFILE-&gt;put()</a>
                </td>
                <td>Return a page to a memory pool</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempfsync.html" class="olink">DB_MPOOLFILE-&gt;sync()</a>
                </td>
                <td>Flush pages from a file in a memory pool</td>
              </tr>
              <tr>
                <td>
                  <span class="emphasis">
                    <em>Memory Pool File Configuration</em>
                  </span>
                </td>
                <td> </td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_clear_len.html" class="olink">DB_MPOOLFILE-&gt;set_clear_len()</a>
                </td>
                <td>Set file page bytes to be cleared</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_fileid.html" class="olink">DB_MPOOLFILE-&gt;set_fileid()</a>
                </td>
                <td>Set file unique identifier</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_flags.html" class="olink">DB_MPOOLFILE-&gt;set_flags()</a>
                </td>
                <td>General memory pool file configuration</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_ftype.html" class="olink">DB_MPOOLFILE-&gt;set_ftype()</a>
                </td>
                <td>Set file type</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_lsn_offset.html" class="olink">DB_MPOOLFILE-&gt;set_lsn_offset()</a>
                </td>
                <td>Set file log-sequence-number offset</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_maxsize.html" class="olink">DB_MPOOLFILE-&gt;set_maxsize()</a>
                </td>
                <td>Set maximum file size</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_pgcookie.html" class="olink">DB_MPOOLFILE-&gt;set_pgcookie()</a>
                </td>
                <td>Set file cookie for pgin/pgout</td>
              </tr>
              <tr>
                <td>
                  <a href="../api_reference/C/mempset_priority.html" class="olink">mempset_priority()</a>
                </td>
                <td>Set memory pool file priority</td>
              </tr>
            </tbody>
          </table>
        </div>
      </div>
    </div>
    <div class="navfooter">
      <hr />
      <table width="100%" summary="Navigation footer">
        <tr>
          <td width="40%" align="left"><a accesskey="p" href="log_limits.html">Prev</a> </td>
          <td width="20%" align="center"> </td>
          <td width="40%" align="right"> <a accesskey="n" href="mp_config.html">Next</a></td>
        </tr>
        <tr>
          <td width="40%" align="left" valign="top">Log file limits </td>
          <td width="20%" align="center">
            <a accesskey="h" href="index.html">Home</a>
          </td>
          <td width="40%" align="right" valign="top"> Configuring the memory pool</td>
        </tr>
      </table>
    </div>
  </body>
</html>
